<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
  <title>DF Raw Parser Help</title>


  <style type="text/css">
div.content {width:70%; margin:auto;}
p {text-indent:30pt;}
  </style></head>

<body>
<div class="content">
<center>
<h1>DF Raw Parser Help</h1>
<br>
<b><u>Version 1.10</u></b>
</center>
<br>
<br>
<center>
<h3>Table of Contents</h3>
<a href="#about">About</a>
<br>
<a href="#basicuse">Basic Use</a>
<br>
<a href="#basicconcepts">Tutorial - Basic Concepts</a>
<br>
<a href="#interface">Tutorial - The Interface</a>
<br>
<a href="#myfirsttags">Tutorial - My First Tags</a>
<br>
<a href="#complextags">Tutorial - More Complex Tags</a>
</center>
<br>
<br>
<br>
<a name="basicconcepts"><h4>About</h4></a>
<p>DF Raw Parser is a
cross-platform application, used to convert the
&ldquo;raw&rdquo; files used by Dwarf Fortress to and from XML
format. The idea formed after I wrote a program that converted the
world history and site/population files from Dwarf Fortress into XML
format. However, the sheer number of tags that can be used in a raw
file made this appear a daunting task, and much of it may become
obsolete with new releases. As such, the program is designed to allow
the user to define/describe a list of tags which are used to parse the
raw/xml files.</p>
<p>The interface is designed to be
as simple as I could make it, while allowing enough power to be able to
modify it to parse any tag without hard-coded help. This means that, in
the event that I can no longer support the tool, it will still be
useful in all future versions, unless the format is changed entirely.
Just in case, I will also be releasing the source publicly, to allow
the future development in my absense.</p>
<br>
<hr>
<br>
<a name="basicuse"><h4>Basic Use</h4></a>
<p>If you don't care about
editing/creating tag lists, then this is really the only section you'll
need to read. DF Raw Parser works by using a list of tags (which
contain information about the tags/tokens in a raw file) to convert a
raw file into XML format, or vice-versa. I've written a tutorial below
that will guide those interested through the creation of tags, but for
those that just need to use the program with existing tag-lists to
parse an XML file, here's how that's done:</p><p>
</p><ol>
<li>If you haven't already, open DF Raw Parser.</li>
<li>Click <i>File-&gt;Load Tag List</i>,
then locate and open (in the dialog that appears) the tag-list you want
to use. Some tag-lists may only work with specific files, or certain
parts of the raws, so if it was a user-generated one, make sure you
know what it's for. The included list, "<i>default.tl</i>" will only parse the creature raws.</li>
<li>Once the tag-list loads, look near the bottom of the application for a button labeled "To XML", and click it.</li>
<li>Another file dialog will appear, find the raw file you want to convert to XML and "Open" it.</li>
<li>The program will now run
through every tag in the file, so if it's a really big one it may take
a little while, depending on the speed of your computer. In that case,
the loading bar below the buttons will display the program's progress.</li>
<li>Once it finishes, there will
be a file in the same folder as the parsed file, with the same name,
but the .XML extension. This is the finished file, so open it up, maybe
double check it for syntax errors, and enjoy!</li>
</ol>
<br>
<p>You can also follow the same steps, but use the "To RAW" button, to convert the XML file back into RAW format.</p>
<br>
<hr>
<br>
<a name="basicconcepts"><h4>Tutorial - Basic Concepts</h4></a>
<p>DF Raw Parser is based on a few simple concepts:</p>
<ul>
<li>Tags: A tag contains the information necessary to process a single tag (or &ldquo;<i>token</i>&rdquo;)
in a raw file. This includes the names of the arguments/attributes, as
well as the types of tag that can be found as children of the tag.</li>
<li>Tag-list: A tag list is a file containing all the tags required to parse a given type of raw file.</li>
<li>Parsing: By parsing, I refer to taking the information out of the raw file, and outputting it in XML format (or vice-versa).</li>
<li>Child Tag: A tag is a child of another if the information it contains is
pertaining to another, previous tag. I.E. The [NAME:?:?:?] tag within a
creature definition.</li>
<li>Argument: An argument is the information contained in a tag, besides it's name. I.E. The number in [TILE:136]</li>
</ul>
<br>
<hr>
<br>
<a name="interface"><h4>Tutorial - The Interface</h4></a>
<p>The interface consists of three
(3) list boxes, and a set of simple controls to go with each, as well
as a tool-bar and two parse buttons.</p>
<u>The Tool-Bar</u>
<p>The tool-bar has two drop-down
menus, that are fairly standard to modern applications. The first is
"File" the second "Help". The following menu options can be found on
the tool-bar:</p>
<ul>
<li>File
<ul>
<li>New Tag List: Closes the current tag list <b>without</b> saving, to start a new file.</li>
<li>Save Tag List: Opens a file dialog that lets you save the current tags to a list file.</li>
<li>Load Tag List: Opens a file dialot that lets you open a tag list file.</li>
<li>Quit: Closes the program.</li>
</ul>
</li><li>Help
<ul>
<li>Help: Opens this file.</li>
<li>About: Displays build information.</li>
</ul>
</li></ul>
<br>
<u>The Tags Panel</u>
<p>The tags panel displays a list
of tags, as well as buttons to add and remove tags. A tag in the list
can be re-named by double-clicking on it. To make changes to a tag
beyond it's name (arguments, children) select (single-click) it, and
then use the other panels. To add a tag, enter the name you want it to
have in the text-box, then click the button labeled "Add Tag". To
remove a tag, select it, and click the button labeled "Delete Tag".</p>
<br>
<u>The Arguments Panel</u>
<p>The arguments panel allows you
to add, remove, and rename the arguments in the current tag. Renaming
is done, as with the tags panel, by double clicking. To add a new tag,
enter the name of the new tag in the box, and click the "Add Argument"
button. To remove an argument from a tag, selected the argument and
click the button labeled "Delete Argument".</p>
<br>
<u>The Children Panel</u>
<p>The children panel is almost
identical to the arguments panel, except that it allows the editing of
a tags children, rather than it's arguments. However, the children
panel has an extra button: "Copy All". Clicking this button copies
every tag into the selected tag's child list. Be careful using this,
and make sure to go back and remove those that are not valid children.</p>
<br>
<u>The Parse Buttons</u>
<p>There are two parse buttons,
one labeled "To XML", the other labeled "To RAW". &nbsp;Their use
is fairly self explanitory. To convert a RAW file <u>to XML</u> click the one labeled "To XML". To convert an XML file <u>to RAW</u> click the one labeled "To RAW".</p>
<br>
<u>The Checkboxes</u>
<p>The checkboxes near the parsing
buttons allow you to have the program apply some basic formatting when
converting files to/from RAW/XML. The RAW checkbox makes the program
capitalize all RAW tag names, while the XML checkbox makes the program
make all XML tag names lowercase.
<br>
</p><hr>
<br>
<a name="myfirsttags"><h4>Tutorial - My First Tags</h4></a>
<p>If you haven't already, open DF
Raw Parser. You should be greeted by a standard window with three large
list-boxes, and several buttons and text-boxes. I already covered the
different parts of the interface, so if you haven't already, go back
and read the <a href="#interface">interface</a>
section. Once you're ready, locate your "creature_amphibians.txt" file
(should be in \DwarfFortress\raw\objects\) and make a copy somewhere
easy to find, like your desktop.</p>
<p>The simplest possible tag to parse, is one with no children, and no arguments; "<i>creature_amphibians.txt</i>" has several of these. The first of which is the "<i>[VERMIN_GROUNDER]</i>"
tag. To begin, start a new file in DF Raw Parser. Now stay with me
here, this gets really complicated... type the name of the tag
("VERMIN_GROUNDER") into the text-box next to the "Add Tag" button
(make sure you clear the original contents first), then click the "Add
Tag" button. Done, simple as that.</p>
<p>Something to take note of, the
name of the tag is not case-sensitive when checked against one in a
file, but the capitalization used in
the "New Tag" box is what will be used when generating the tags for
it. Because XML is usually lower-case, let's go ahead and change it.
(The checkboxes at the bottom makes this unneccesary, but do it
anyways, so you can get used to the program.) Double click on
the tag name in the list-box and a simple dialog with two text-boxes
will
appear. The first is the name of the tag as it is checked/output in RAW
files, while the second is the name of the tag as it is checked/output
in XML files. Retype the name in lower-case
("vermin_grounder") in the second box, and click the
okay button.</p>
<p>Now we'll move on to something slightly more complex... a tag with arguments. The first two of these in "<i>creature_amphibians.txt</i>" file are "<i>[OBJECT:CREATURE]</i>" and "<i>[CREATURE:TOAD]</i>", but both of these have children, so we'll use the "<i>[NAME:?:?:?]</i>"
tag as our first example. Start by adding a new tag called
"NAME".Before we can add the arguments to the tag, we need to know what
they are. A quick search on the <a href="df.magmawiki.com">DF Wiki</a>
reveals that they are the singular, plural, and adjective versions of
the name. So now we just need to add these to the tag. This is done
much the same as adding a tag, but before you can add an argument to a
tag, it has to be selected. Single click on the name of the tag to
highlight it, then enter "singular" into the "New Argument" box, and
click the "Add Argument" button. Repeat for the other arguments. Note
that unlike tags, there is no right or wrong name for arguments, they
can be called whatever you want, and are only used when writing to or reading from XML files.</p>
<p>Now we'll add a tag with
children. Create a new tag for the [CREATURE:?] tag ("creature") and
select it. The children of a tag are the names of tags that can be
found within the tag, like the name, tile, etc. tags in the "<i>creature_amphibians.txt</i>"
file to the [CREATURE:?] tag. When generating XML, the program knows to
start a new tag when it finds a matching one, but when a tag is
supposed to have children, it also needs to know when to close it. It
does this by leaving the tag open until it finds a tag that cannot be
it's child. For now, add two children: one for the "vermin_grounder"
tag, and one for the "name" tag. Eventually, you will need a child
listing for every tag that can be a part of a creature, but for now
those two will do.</p>
<p>Before we continue, you'll want to save your tag-list. Click <i>File-&gt;Save Tag List</i>
then choose a name for your file, and put it somewhere you can find it
later. Now we'll go ahead and test the tag-list. Click the "To XML"
button, locate the copy of the "<i>creature_amphibians.txt</i>"
file, and click "Open". There may be a slight delay depending on the
speed of your computer (and the size of the file being parsed, if you
used something other than "<i>creature_amphibians.txt</i>"),
and then an XML file will appear in the same directory with the same
name as the parsed file. Go ahead and open it, make sure everything
looks how you want it to, and pat yourself on the back.</p>
<br>
<hr>
<br>
<a name="complextags"><h4>Tutorial - More Complex Tags</h4></a>
<p>For the most part, the above
steps can be applied to the rest of the tags for any file, and the
program will function just fine. But there are a couple more complex
tags that merit mention. The first is the "<i>[BODY]</i>"
tag. In the any one example it looks innocent enough, but it often
times has more or less arguments. So how do you deal with a tag with an
arbitrary number of arguments? It's really easy. Go ahead and add a tag
for "<i>[BODY]</i>",
then give it a single argument: "part". When parsing the raw files, if
the program encounters more arguments than expected, it uses the last
listed argument name for all of them. So when parsing the tag "<i>[BODY:QUADRUPED:TAIL:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:THROAT:NECK:SPINE:BRAIN:MOUTH]</i>" the resulting XML would be:</p>
<pre>&lt;body&gt;<br>	&lt;part&gt;tail&lt;/part&gt;<br>	&lt;part&gt;2eyes&lt;/part&gt;<br>	&lt;part&gt;2ears&lt;/part&gt;<br>	&lt;part&gt;nose&lt;/part&gt;<br>	&lt;part&gt;etc...&lt;/part&gt;<br>&lt;/body&gt;</pre>
<p>The last thing of note, is that
a tag's list of children should only hold children that can be a direct
child to the tag. For example, the [CREATURE] tag is a child of the
[OBJECT] tag, but the [NAME] tag isn't. They are both under the
[OBJECT] tag, but the [NAME] tag is under the [CREATURE] tag, and
cannot be found outside of it, by itself in the [OBJECT] tag.</p>
</div>

</body></html>